aiobungie

70@attrs.define(auto_exc=True)
71class AiobungieError(RuntimeError):
72    """Base class that all other exceptions inherit from."""

635@typing.final
636class AmmoType(int, Enum):
637    """AN enum for Detyiny 2 ammo types."""
638
639    NONE = 0
640    PRIMARY = 1
641    SPECIAL = 2
642    HEAVY = 3

163@attrs.define(auto_exc=True)
164class BadRequest(HTTPError):
165    """An exception raised when requesting a resource with the provided data is wrong."""
166
167    url: typedefs.StrOrURL | None
168    """The URL/endpoint caused this error."""
169
170    body: typing.Any
171    """The response body."""
172
173    headers: multidict.CIMultiDictProxy[str]
174    """The response headers."""
175
176    http_status: http.HTTPStatus = attrs.field(
177        default=http.HTTPStatus.BAD_REQUEST, init=False
178    )

690@typing.final
691class ClanMemberType(int, Enum):
692    """An enum for bungie clan member types."""
693
694    NONE = 0
695    BEGINNER = 1
696    MEMBER = 2
697    ADMIN = 3
698    ACTING_FOUNDER = 4
699    FOUNDER = 5

466@typing.final
467class Class(int, Enum):
468    """An Enum for Destiny character classes."""
469
470    TITAN = 0
471    HUNTER = 1
472    WARLOCK = 2
473    UNKNOWN = 3

  55class Client(traits.ClientApp):
  56    """Standard Bungie API client implementation.
  57
  58    This client deserialize the REST JSON responses using `aiobungie.Factory`
  59    and returns `aiobungie.crates` Python object implementations of the responses.
  60
  61    Example
  62    -------
  63    ```py
  64    import aiobungie
  65
  66    client = aiobungie.Client('...')
  67
  68    async def main():
  69        async with client.rest:
  70            user = await client.fetch_current_user_memberships('...')
  71            print(user)
  72    ```
  73
  74    Parameters
  75    -----------
  76    token: `str`
  77        Your Bungie's API key or Token from the developer's portal.
  78
  79    Other Parameters
  80    ----------------
  81    max_retries : `int`
  82        The max retries number to retry if the request hit a `5xx` status code.
  83    client_secret : `str | None`
  84        An optional application client secret,
  85        This is only needed if you're fetching OAuth2 tokens with this client.
  86    client_id : `int | None`
  87        An optional application client id,
  88        This is only needed if you're fetching OAuth2 tokens with this client.
  89    debug: `"TRACE" | bool | int`
  90        The level of logging to enable.
  91    """
  92
  93    __slots__ = ("_rest", "_factory")
  94
  95    def __init__(
  96        self,
  97        token: str,
  98        /,
  99        *,
 100        client_secret: str | None = None,
 101        client_id: int | None = None,
 102        max_retries: int = 4,
 103        debug: typing.Literal["TRACE"] | bool | int = False,
 104    ) -> None:
 105        self._rest = rest_.RESTClient(
 106            token,
 107            client_secret=client_secret,
 108            client_id=client_id,
 109            max_retries=max_retries,
 110            debug=debug,
 111        )
 112
 113        self._factory = factory_.Factory(self)
 114
 115    @property
 116    def factory(self) -> factory_.Factory:
 117        return self._factory
 118
 119    @property
 120    def rest(self) -> interfaces.RESTInterface:
 121        return self._rest
 122
 123    @property
 124    def request(self) -> Client:
 125        return self
 126
 127    @property
 128    def metadata(self) -> collections.MutableMapping[typing.Any, typing.Any]:
 129        return self._rest.metadata
 130
 131    def run(self, fn: collections.Awaitable[typing.Any], debug: bool = False) -> None:
 132        loop = helpers.get_or_make_loop()
 133
 134        try:
 135            if not loop.is_running():
 136                loop.set_debug(debug)
 137                loop.run_until_complete(fn)
 138
 139        except Exception as exc:
 140            raise RuntimeError(f"Failed to run {fn!s}") from exc
 141
 142    # * User methods.
 143
 144    async def fetch_current_user_memberships(self, access_token: str, /) -> user.User:
 145        """Fetch and return a user object of the bungie net user associated with account.
 146
 147        .. warning::
 148            This method requires OAuth2 scope and a Bearer access token.
 149
 150        Parameters
 151        ----------
 152        access_token : `str`
 153            A valid Bearer access token for the authorization.
 154
 155        Returns
 156        -------
 157        `aiobungie.crates.user.User`
 158            A user object includes the Destiny memberships and Bungie.net user.
 159        """
 160        resp = await self.rest.fetch_current_user_memberships(access_token)
 161
 162        return self.factory.deserialize_user(resp)
 163
 164    async def fetch_bungie_user(self, id: int, /) -> user.BungieUser:
 165        """Fetch a Bungie user by their BungieNet id.
 166
 167        .. note::
 168            This returns a Bungie user membership only. Take a look at `Client.fetch_membership_from_id`
 169            for other memberships.
 170
 171        Parameters
 172        ----------
 173        id: `int`
 174            The user id.
 175
 176        Returns
 177        -------
 178        `aiobungie.crates.user.BungieUser`
 179            A Bungie user.
 180
 181        Raises
 182        ------
 183        `aiobungie.error.NotFound`
 184            The user was not found.
 185        """
 186        payload = await self.rest.fetch_bungie_user(id)
 187
 188        return self.factory.deserialize_bungie_user(payload)
 189
 190    async def search_users(
 191        self, name: str, /
 192    ) -> iterators.Iterator[user.SearchableDestinyUser]:
 193        """Search for players and return all players that matches the same name.
 194
 195        Parameters
 196        ----------
 197        name : `str`
 198            The user name.
 199
 200        Returns
 201        -------
 202        `aiobungie.Iterator[aiobungie.crates.SearchableDestinyUser]`
 203            A sequence of the found users with this name.
 204        """
 205        payload = await self.rest.search_users(name)
 206
 207        return iterators.Iterator(
 208            [
 209                self.factory.deserialize_searched_user(user)
 210                for user in payload["searchResults"]
 211            ]
 212        )
 213
 214    async def fetch_user_themes(self) -> collections.Sequence[user.UserThemes]:
 215        """Fetch all available user themes.
 216
 217        Returns
 218        -------
 219        `collections.Sequence[aiobungie.crates.user.UserThemes]`
 220            A sequence of user themes.
 221        """
 222        data = await self.rest.fetch_user_themes()
 223
 224        return self.factory.deserialize_user_themes(data)
 225
 226    async def fetch_hard_types(
 227        self,
 228        credential: int,
 229        type: enums.CredentialType | int = enums.CredentialType.STEAMID,
 230        /,
 231    ) -> user.HardLinkedMembership:
 232        """Gets any hard linked membership given a credential.
 233        Only works for credentials that are public just `aiobungie.CredentialType.STEAMID` right now.
 234        Cross Save aware.
 235
 236        Parameters
 237        ----------
 238        credential: `int`
 239            A valid SteamID64
 240        type: `aiobungie.CredentialType`
 241            The credential type. This must not be changed
 242            Since its only credential that works "currently"
 243
 244        Returns
 245        -------
 246        `aiobungie.crates.user.HardLinkedMembership`
 247            Information about the hard linked data.
 248        """
 249
 250        payload = await self.rest.fetch_hardlinked_credentials(credential, type)
 251
 252        return user.HardLinkedMembership(
 253            id=int(payload["membershipId"]),
 254            type=enums.MembershipType(payload["membershipType"]),
 255            cross_save_type=enums.MembershipType(payload["CrossSaveOverriddenType"]),
 256        )
 257
 258    async def fetch_membership_from_id(
 259        self,
 260        id: int,
 261        /,
 262        type: enums.MembershipType | int = enums.MembershipType.NONE,
 263    ) -> user.User:
 264        """Fetch Bungie user's memberships from their id.
 265
 266        Notes
 267        -----
 268        * This returns both BungieNet membership and a sequence of the player's DestinyMemberships
 269        Which includes Stadia, Xbox, Steam and PSN memberships if the player has them,
 270        see `aiobungie.crates.user.DestinyMembership` for more details.
 271        * If you only want the bungie user. Consider using `Client.fetch_user` method.
 272
 273        Parameters
 274        ----------
 275        id : `int`
 276            The user's id.
 277        type : `aiobungie.MembershipType`
 278            The user's membership type.
 279
 280        Returns
 281        -------
 282        `aiobungie.crates.User`
 283            A Bungie user with their membership types.
 284
 285        Raises
 286        ------
 287        aiobungie.NotFound
 288            The requested user was not found.
 289        """
 290        payload = await self.rest.fetch_membership_from_id(id, type)
 291
 292        return self.factory.deserialize_user(payload)
 293
 294    async def fetch_user_credentials(
 295        self, access_token: str, membership_id: int, /
 296    ) -> collections.Sequence[user.UserCredentials]:
 297        """Fetch an array of credential types attached to the requested account.
 298
 299        .. note::
 300            This method require OAuth2 Bearer access token.
 301
 302        Parameters
 303        ----------
 304        access_token : `str`
 305            The bearer access token associated with the bungie account.
 306        membership_id : `int`
 307            The id of the membership to return.
 308
 309        Returns
 310        -------
 311        `collections.Sequence[aiobungie.crates.UserCredentials]`
 312            A sequence of the attached user credentials.
 313
 314        Raises
 315        ------
 316        `aiobungie.Unauthorized`
 317            The access token was wrong or no access token passed.
 318        """
 319        resp = await self.rest.fetch_user_credentials(access_token, membership_id)
 320
 321        return self.factory.deserialize_user_credentials(resp)
 322
 323    # * Destiny 2.
 324
 325    async def fetch_profile(
 326        self,
 327        member_id: int,
 328        type: enums.MembershipType | int,
 329        components: collections.Sequence[enums.ComponentType],
 330        auth: str | None = None,
 331    ) -> components.Component:
 332        """
 333        Fetch a bungie profile passing components to the request.
 334
 335        Parameters
 336        ----------
 337        member_id: `int`
 338            The member's id.
 339        type: `aiobungie.MembershipType`
 340            A valid membership type.
 341        components : `collections.Sequence[aiobungie.ComponentType]`
 342            List of profile components to collect and return.
 343
 344        Other Parameters
 345        ----------------
 346        auth : `str | None`
 347            A Bearer access_token to make the request with.
 348            This is optional and limited to components that only requires an Authorization token.
 349
 350        Returns
 351        --------
 352        `aiobungie.crates.Component`
 353            A Destiny 2 player profile with its components.
 354            Only passed components will be available if they exists. Otherwise they will be `None`
 355
 356        Raises
 357        ------
 358        `aiobungie.MembershipTypeError`
 359            The provided membership type was invalid.
 360        """
 361        data = await self.rest.fetch_profile(member_id, type, components, auth)
 362        return self.factory.deserialize_components(data)
 363
 364    async def fetch_linked_profiles(
 365        self,
 366        member_id: int,
 367        member_type: enums.MembershipType | int,
 368        /,
 369        *,
 370        all: bool = False,
 371    ) -> profile.LinkedProfile:
 372        """Returns a summary information about all profiles linked to the requested member.
 373
 374        The passed membership id/type maybe a Bungie.Net membership or a Destiny memberships.
 375
 376        .. note::
 377            It will only return linked accounts whose linkages you are allowed to view.
 378
 379        Parameters
 380        ----------
 381        member_id : `int`
 382            The ID of the membership. This must be a valid Bungie.Net or PSN or Xbox ID.
 383        member_type : `aiobungie.MembershipType`
 384            The type for the membership whose linked Destiny account you want to return.
 385
 386        Other Parameters
 387        ----------------
 388        all : `bool`
 389            If provided and set to `True`, All memberships regardless
 390            of whether they're obscured by overrides will be returned,
 391
 392            If provided and set to `False`, Only available memberships will be returned.
 393            The default for this is `False`.
 394
 395        Returns
 396        -------
 397        `aiobungie.crates.profile.LinkedProfile`
 398            A linked profile object.
 399        """
 400        resp = await self.rest.fetch_linked_profiles(member_id, member_type, all=all)
 401
 402        return self.factory.deserialize_linked_profiles(resp)
 403
 404    async def fetch_membership(
 405        self,
 406        name: str,
 407        code: int,
 408        /,
 409        type: enums.MembershipType | int = enums.MembershipType.ALL,
 410    ) -> collections.Sequence[user.DestinyMembership]:
 411        """Fetch a Destiny 2 player's memberships.
 412
 413        Parameters
 414        -----------
 415        name: `str`
 416            The unique Bungie player name.
 417        code : `int`
 418            The unique Bungie display name code.
 419        type: `aiobungie.internal.enums.MembershipType`
 420            The player's membership type, e,g. XBOX, STEAM, PSN
 421
 422        Returns
 423        --------
 424        `collections.Sequence[aiobungie.crates.DestinyMembership]`
 425            A sequence of the found Destiny 2 player memberships.
 426            An empty sequence will be returned if no one found.
 427
 428        Raises
 429        ------
 430        `aiobungie.MembershipTypeError`
 431            The provided membership type was invalid.
 432        """
 433        resp = await self.rest.fetch_membership(name, code, type)
 434
 435        return self.factory.deserialize_destiny_memberships(resp)
 436
 437    async def fetch_character(
 438        self,
 439        member_id: int,
 440        membership_type: enums.MembershipType | int,
 441        character_id: int,
 442        components: collections.Sequence[enums.ComponentType],
 443        auth: str | None = None,
 444    ) -> components.CharacterComponent:
 445        """Fetch a Destiny 2 character.
 446
 447        Parameters
 448        ----------
 449        member_id: `int`
 450            A valid bungie member id.
 451        character_id: `int`
 452            The Destiny character id to retrieve.
 453        membership_type: `aiobungie.internal.enums.MembershipType`
 454            The member's membership type.
 455        components: `collections.Sequence[aiobungie.ComponentType]`
 456            Multiple arguments of character components to collect and return.
 457
 458        Other Parameters
 459        ----------------
 460        auth : `str | None`
 461            A Bearer access_token to make the request with.
 462            This is optional and limited to components that only requires an Authorization token.
 463
 464        Returns
 465        -------
 466        `aiobungie.crates.CharacterComponent`
 467            A Bungie character component.
 468
 469        `aiobungie.MembershipTypeError`
 470            The provided membership type was invalid.
 471        """
 472        resp = await self.rest.fetch_character(
 473            member_id, membership_type, character_id, components, auth
 474        )
 475
 476        return self.factory.deserialize_character_component(resp)
 477
 478    async def fetch_unique_weapon_history(
 479        self,
 480        membership_id: int,
 481        character_id: int,
 482        membership_type: enums.MembershipType | int,
 483    ) -> collections.Sequence[activity.ExtendedWeaponValues]:
 484        """Fetch details about unique weapon usage for a character. Includes all exotics.
 485
 486        Parameters
 487        ----------
 488        membership_id : `int`
 489            The Destiny user membership id.
 490        character_id : `int`
 491            The character id to retrieve.
 492        membership_type : `aiobungie.aiobungie.MembershipType | int`
 493            The Destiny user's membership type.
 494
 495        Returns
 496        -------
 497        `collections.Sequence[aiobungie.crates.ExtendedWeaponValues]`
 498            A sequence of the weapon's extended values.
 499        """
 500        resp = await self._rest.fetch_unique_weapon_history(
 501            membership_id, character_id, membership_type
 502        )
 503
 504        return tuple(
 505            self._factory.deserialize_extended_weapon_values(weapon)
 506            for weapon in resp["weapons"]
 507        )
 508
 509    # * Destiny 2 Activities.
 510
 511    async def fetch_activities(
 512        self,
 513        member_id: int,
 514        character_id: int,
 515        mode: enums.GameMode | int,
 516        *,
 517        membership_type: enums.MembershipType | int = enums.MembershipType.ALL,
 518        page: int = 0,
 519        limit: int = 250,
 520    ) -> iterators.Iterator[activity.Activity]:
 521        """Fetch a Destiny 2 activity for the specified character id.
 522
 523        Parameters
 524        ----------
 525        member_id: `int`
 526            The user id that starts with `4611`.
 527        character_id: `int`
 528            The id of the character to retrieve the activities for.
 529        mode: `aiobungie.aiobungie.internal.enums.GameMode | int`
 530            This parameter filters the game mode, Nightfall, Strike, Iron Banner, etc.
 531
 532        Other Parameters
 533        ----------------
 534        membership_type: `aiobungie.internal.enums.MembershipType`
 535            The Member ship type, if nothing was passed than it will return all.
 536        page: int
 537            The page number. Default is `0`
 538        limit: int
 539            Limit the returned result. Default is `250`.
 540
 541        Returns
 542        -------
 543        `aiobungie.Iterator[aiobungie.crates.Activity]`
 544            An iterator of the player's activities.
 545
 546        Raises
 547        ------
 548        `aiobungie.MembershipTypeError`
 549            The provided membership type was invalid.
 550        """
 551        resp = await self.rest.fetch_activities(
 552            member_id,
 553            character_id,
 554            mode,
 555            membership_type=membership_type,
 556            page=page,
 557            limit=limit,
 558        )
 559
 560        return self.factory.deserialize_activities(resp)
 561
 562    async def fetch_post_activity(self, instance_id: int, /) -> activity.PostActivity:
 563        """Fetch a post activity details.
 564
 565        Parameters
 566        ----------
 567        instance_id: `int`
 568            The activity instance id.
 569
 570        Returns
 571        -------
 572        `aiobungie.crates.PostActivity`
 573           A post activity object.
 574        """
 575        resp = await self.rest.fetch_post_activity(instance_id)
 576
 577        return self.factory.deserialize_post_activity(resp)
 578
 579    async def fetch_aggregated_activity_stats(
 580        self,
 581        character_id: int,
 582        membership_id: int,
 583        membership_type: enums.MembershipType | int,
 584    ) -> iterators.Iterator[activity.AggregatedActivity]:
 585        """Fetch aggregated activity stats for a character.
 586
 587        Parameters
 588        ----------
 589        character_id: `int`
 590            The id of the character to retrieve the activities for.
 591        membership_id: `int`
 592            The id of the user that started with `4611`.
 593        membership_type: `aiobungie.internal.enums.MembershipType`
 594            The Member ship type.
 595
 596        Returns
 597        -------
 598        `aiobungie.Iterator[aiobungie.crates.AggregatedActivity]`
 599            An iterator of the player's activities.
 600
 601        Raises
 602        ------
 603        `aiobungie.MembershipTypeError`
 604            The provided membership type was invalid.
 605        """
 606        resp = await self.rest.fetch_aggregated_activity_stats(
 607            character_id, membership_id, membership_type
 608        )
 609
 610        return self.factory.deserialize_aggregated_activities(resp)
 611
 612    # * Destiny 2 Clans or GroupsV2.
 613
 614    async def fetch_clan_from_id(
 615        self,
 616        id: int,
 617        /,
 618        access_token: str | None = None,
 619    ) -> clans.Clan:
 620        """Fetch a Bungie Clan by its id.
 621
 622        Parameters
 623        -----------
 624        id: `int`
 625            The clan id.
 626
 627        Returns
 628        --------
 629        `aiobungie.crates.Clan`
 630            An Bungie clan.
 631
 632        Raises
 633        ------
 634        `aiobungie.NotFound`
 635            The clan was not found.
 636        """
 637        resp = await self.rest.fetch_clan_from_id(id, access_token)
 638
 639        return self.factory.deserialize_clan(resp)
 640
 641    async def fetch_clan(
 642        self,
 643        name: str,
 644        /,
 645        access_token: str | None = None,
 646        *,
 647        type: enums.GroupType | int = enums.GroupType.CLAN,
 648    ) -> clans.Clan:
 649        """Fetch a Clan by its name.
 650        This method will return the first clan found with given name.
 651
 652        Parameters
 653        ----------
 654        name: `str`
 655            The clan name
 656
 657        Other Parameters
 658        ----------------
 659        access_token : `str | None`
 660            An optional access token to make the request with.
 661
 662            If the token was bound to a member of the clan,
 663            This field `aiobungie.crates.Clan.current_user_membership` will be available
 664            and will return the membership of the user who made this request.
 665        type : `aiobungie.GroupType`
 666            The group type, Default is aiobungie.GroupType.CLAN.
 667
 668        Returns
 669        -------
 670        `aiobungie.crates.Clan`
 671            A Bungie clan.
 672
 673        Raises
 674        ------
 675        `aiobungie.NotFound`
 676            The clan was not found.
 677        """
 678        resp = await self.rest.fetch_clan(name, access_token, type=type)
 679
 680        return self.factory.deserialize_clan(resp)
 681
 682    async def fetch_clan_conversations(
 683        self, clan_id: int, /
 684    ) -> collections.Sequence[clans.ClanConversation]:
 685        """Fetch the conversations/chat channels of the given clan id.
 686
 687        Parameters
 688        ----------
 689        clan_id : `int`
 690            The clan id.
 691
 692        Returns
 693        `collections.Sequence[aiobungie.crates.ClanConversation]`
 694            A sequence of the clan chat channels.
 695        """
 696        resp = await self.rest.fetch_clan_conversations(clan_id)
 697
 698        return self.factory.deserialize_clan_conversations(resp)
 699
 700    async def fetch_clan_admins(
 701        self, clan_id: int, /
 702    ) -> iterators.Iterator[clans.ClanMember]:
 703        """Fetch the clan founder and admins.
 704
 705        Parameters
 706        ----------
 707        clan_id : `int`
 708            The clan id.
 709
 710        Returns
 711        -------
 712        `aiobungie.Iterator[aiobungie.crates.ClanMember]`
 713            An iterator over the found clan admins and founder.
 714
 715        Raises
 716        ------
 717        `aiobungie.NotFound`
 718            The requested clan was not found.
 719        """
 720        resp = await self.rest.fetch_clan_admins(clan_id)
 721
 722        return self.factory.deserialize_clan_members(resp)
 723
 724    async def fetch_groups_for_member(
 725        self,
 726        member_id: int,
 727        member_type: enums.MembershipType | int,
 728        /,
 729        *,
 730        filter: int = 0,
 731        group_type: enums.GroupType = enums.GroupType.CLAN,
 732    ) -> collections.Sequence[clans.GroupMember]:
 733        """Fetch information about the groups that a given member has joined.
 734
 735        Parameters
 736        ----------
 737        member_id : `int`
 738            The member's id
 739        member_type : `aiobungie.MembershipType`
 740            The member's membership type.
 741
 742        Other Parameters
 743        ----------------
 744        filter : `int`
 745            Filter apply to list of joined groups. This Default to `0`
 746        group_type : `aiobungie.GroupType`
 747            The group's type.
 748            This is always set to `aiobungie.GroupType.CLAN` and should not be changed.
 749
 750        Returns
 751        -------
 752        `collections.Sequence[aiobungie.crates.GroupMember]`
 753            A sequence of joined groups for the fetched member.
 754        """
 755        resp = await self.rest.fetch_groups_for_member(
 756            member_id, member_type, filter=filter, group_type=group_type
 757        )
 758
 759        return tuple(
 760            self.factory.deserialize_group_member(group) for group in resp["results"]
 761        )
 762
 763    async def fetch_potential_groups_for_member(
 764        self,
 765        member_id: int,
 766        member_type: enums.MembershipType | int,
 767        /,
 768        *,
 769        filter: int = 0,
 770        group_type: enums.GroupType | int = enums.GroupType.CLAN,
 771    ) -> collections.Sequence[clans.GroupMember]:
 772        """Fetch the potential groups for a clan member.
 773
 774        Parameters
 775        ----------
 776        member_id : `int`
 777            The member's id
 778        member_type : `aiobungie.aiobungie.MembershipType | int`
 779            The member's membership type.
 780
 781        Other Parameters
 782        ----------------
 783        filter : `int`
 784            Filter apply to list of joined groups. This Default to `0`
 785        group_type : `aiobungie.aiobungie.GroupType | int`
 786            The group's type.
 787            This is always set to `aiobungie.GroupType.CLAN` and should not be changed.
 788
 789        Returns
 790        -------
 791        `collections.Sequence[aiobungie.crates.GroupMember]`
 792            A sequence of joined potential groups for the fetched member.
 793        """
 794        resp = await self.rest.fetch_potential_groups_for_member(
 795            member_id, member_type, filter=filter, group_type=group_type
 796        )
 797
 798        return tuple(
 799            self.factory.deserialize_group_member(group) for group in resp["results"]
 800        )
 801
 802    async def fetch_clan_members(
 803        self,
 804        clan_id: int,
 805        /,
 806        *,
 807        name: str | None = None,
 808        type: enums.MembershipType | int = enums.MembershipType.NONE,
 809    ) -> iterators.Iterator[clans.ClanMember]:
 810        """Fetch Bungie clan members.
 811
 812        Parameters
 813        ----------
 814        clan_id : `int`
 815            The clans id
 816
 817        Other Parameters
 818        ----------------
 819        name : `str | None`
 820            If provided, Only players matching this name will be returned.
 821        type : `aiobungie.MembershipType`
 822            An optional clan member's membership type.
 823            This parameter is used to filter the returned results
 824            by the provided membership, For an example XBox memberships only,
 825            Otherwise will return all memberships.
 826
 827        Returns
 828        -------
 829        `aiobungie.Iterator[aiobungie.crates.ClanMember]`
 830            An iterator over the bungie clan members.
 831
 832        Raises
 833        ------
 834        `aiobungie.NotFound`
 835            The clan was not found.
 836        """
 837        resp = await self.rest.fetch_clan_members(clan_id, type=type, name=name)
 838
 839        return self.factory.deserialize_clan_members(resp)
 840
 841    async def fetch_clan_banners(self) -> collections.Sequence[clans.ClanBanner]:
 842        """Fetch the clan banners.
 843
 844        Returns
 845        -------
 846        `collections.Sequence[aiobungie.crates.ClanBanner]`
 847            A sequence of the clan banners.
 848        """
 849        resp = await self.rest.fetch_clan_banners()
 850
 851        return self.factory.deserialize_clan_banners(resp)
 852
 853    # This method is required to be here since it deserialize the clan.
 854    async def kick_clan_member(
 855        self,
 856        access_token: str,
 857        /,
 858        group_id: int,
 859        membership_id: int,
 860        membership_type: enums.MembershipType | int,
 861    ) -> clans.Clan:
 862        """Kick a member from the clan.
 863
 864        .. note::
 865            This request requires OAuth2: oauth2: `AdminGroups` scope.
 866
 867        Parameters
 868        ----------
 869        access_token : `str`
 870            The bearer access token associated with the bungie account.
 871        group_id: `int`
 872            The group id.
 873        membership_id : `int`
 874            The member id to kick.
 875        membership_type : `aiobungie.aiobungie.MembershipType | int`
 876            The member's membership type.
 877
 878        Returns
 879        -------
 880        `aiobungie.crates.clan.Clan`
 881            The clan that the member was kicked from.
 882        """
 883        resp = await self.rest.kick_clan_member(
 884            access_token,
 885            group_id=group_id,
 886            membership_id=membership_id,
 887            membership_type=membership_type,
 888        )
 889
 890        return self.factory.deserialize_clan(resp)
 891
 892    async def fetch_clan_weekly_rewards(self, clan_id: int) -> milestones.Milestone:
 893        """Fetch a Bungie clan's weekly reward state.
 894
 895        Parameters
 896        ----------
 897        clan_id : `int`
 898            The clan's id.
 899
 900        Returns
 901        -------
 902        `aiobungie.crates.Milestone`
 903            A runtime status of the clan's milestone data.
 904        """
 905
 906        resp = await self.rest.fetch_clan_weekly_rewards(clan_id)
 907
 908        return self.factory.deserialize_milestone(resp)
 909
 910    # * Destiny 2 Entities aka Definitions.
 911
 912    async def fetch_inventory_item(self, hash: int, /) -> entity.InventoryEntity:
 913        """Fetch a static inventory item entity given a its hash.
 914
 915        Parameters
 916        ----------
 917        hash: `int`
 918            Inventory item's hash.
 919
 920        Returns
 921        -------
 922        `aiobungie.crates.InventoryEntity`
 923            A bungie inventory item.
 924        """
 925        resp = await self.rest.fetch_inventory_item(hash)
 926
 927        return self.factory.deserialize_inventory_entity(resp)
 928
 929    async def fetch_objective_entity(self, hash: int, /) -> entity.ObjectiveEntity:
 930        """Fetch a Destiny objective entity given a its hash.
 931
 932        Parameters
 933        ----------
 934        hash: `int`
 935            objective's hash.
 936
 937        Returns
 938        -------
 939        `aiobungie.crates.ObjectiveEntity`
 940            An objective entity item.
 941        """
 942        resp = await self.rest.fetch_objective_entity(hash)
 943
 944        return self.factory.deserialize_objective_entity(resp)
 945
 946    async def search_entities(
 947        self, name: str, entity_type: str, *, page: int = 0
 948    ) -> iterators.Iterator[entity.SearchableEntity]:
 949        """Search for Destiny2 entities given a name and its type.
 950
 951        Parameters
 952        ----------
 953        name : `str`
 954            The name of the entity, i.e., Thunderlord, One thousand voices.
 955        entity_type : `str`
 956            The type of the entity, AKA Definition,
 957            For an example `DestinyInventoryItemDefinition` for emblems, weapons, and other inventory items.
 958
 959        Other Parameters
 960        ----------------
 961        page : `int`
 962            An optional page to return. Default to 0.
 963
 964        Returns
 965        -------
 966        `aiobungie.Iterator[aiobungie.crates.SearchableEntity]`
 967            An iterator over the found results matching the provided name.
 968        """
 969        resp = await self.rest.search_entities(name, entity_type, page=page)
 970
 971        return self.factory.deserialize_inventory_results(resp)
 972
 973    # Fireteams
 974
 975    async def fetch_fireteams(
 976        self,
 977        activity_type: fireteams.FireteamActivity | int,
 978        *,
 979        platform: fireteams.FireteamPlatform | int = fireteams.FireteamPlatform.ANY,
 980        language: fireteams.FireteamLanguage | str = fireteams.FireteamLanguage.ALL,
 981        date_range: int = 0,
 982        page: int = 0,
 983        slots_filter: int = 0,
 984    ) -> collections.Sequence[fireteams.Fireteam]:
 985        """Fetch public Bungie fireteams with open slots.
 986
 987        Parameters
 988        ----------
 989        activity_type : `aiobungie.aiobungie.crates.FireteamActivity | int`
 990            The fireteam activity type.
 991
 992        Other Parameters
 993        ----------------
 994        platform : `aiobungie.aiobungie.crates.fireteams.FireteamPlatform | int`
 995            If this is provided. Then the results will be filtered with the given platform.
 996            Defaults to `aiobungie.crates.FireteamPlatform.ANY` which returns all platforms.
 997        language : `aiobungie.crates.fireteams.FireteamLanguage | str`
 998            A locale language to filter the used language in that fireteam.
 999            Defaults to `aiobungie.crates.FireteamLanguage.ALL`
1000        date_range : `int`
1001            An integer to filter the date range of the returned fireteams. Defaults to `aiobungie.FireteamDate.ALL`.
1002        page : `int`
1003            The page number. By default its `0` which returns all available activities.
1004        slots_filter : `int`
1005            Filter the returned fireteams based on available slots. Default is `0`
1006
1007        Returns
1008        -------
1009        `collections.Sequence[fireteams.Fireteam]`
1010            A sequence of `aiobungie.crates.Fireteam`.
1011        """
1012
1013        resp = await self.rest.fetch_fireteams(
1014            activity_type,
1015            platform=platform,
1016            language=language,
1017            date_range=date_range,
1018            page=page,
1019            slots_filter=slots_filter,
1020        )
1021
1022        return self.factory.deserialize_fireteams(resp)
1023
1024    async def fetch_available_clan_fireteams(
1025        self,
1026        access_token: str,
1027        group_id: int,
1028        activity_type: fireteams.FireteamActivity | int,
1029        *,
1030        platform: fireteams.FireteamPlatform | int,
1031        language: fireteams.FireteamLanguage | str,
1032        date_range: int = 0,
1033        page: int = 0,
1034        public_only: bool = False,
1035        slots_filter: int = 0,
1036    ) -> collections.Sequence[fireteams.Fireteam]:
1037        """Fetch a clan's fireteams with open slots.
1038
1039        .. note::
1040            This method requires OAuth2: ReadGroups scope.
1041
1042        Parameters
1043        ----------
1044        access_token : `str`
1045            The bearer access token associated with the bungie account.
1046        group_id : `int`
1047            The group/clan id of the fireteam.
1048        activity_type : `aiobungie.aiobungie.crates.FireteamActivity | int`
1049            The fireteam activity type.
1050
1051        Other Parameters
1052        ----------------
1053        platform : `aiobungie.aiobungie.crates.fireteams.FireteamPlatform | int`
1054            If this is provided. Then the results will be filtered with the given platform.
1055            Defaults to `aiobungie.crates.FireteamPlatform.ANY` which returns all platforms.
1056        language : `aiobungie.crates.fireteams.FireteamLanguage | str`
1057            A locale language to filter the used language in that fireteam.
1058            Defaults to `aiobungie.crates.FireteamLanguage.ALL`
1059        date_range : `int`
1060            An integer to filter the date range of the returned fireteams. Defaults to `0`.
1061        page : `int`
1062            The page number. By default its `0` which returns all available activities.
1063        public_only: `bool`
1064            If set to True, Then only public fireteams will be returned.
1065        slots_filter : `int`
1066            Filter the returned fireteams based on available slots. Default is `0`
1067
1068        Returns
1069        -------
1070        `collections.Sequence[aiobungie.crates.Fireteam]`
1071            A sequence of  fireteams found in the clan.
1072            `None` will be returned if nothing was found.
1073        """
1074        resp = await self.rest.fetch_available_clan_fireteams(
1075            access_token,
1076            group_id,
1077            activity_type,
1078            platform=platform,
1079            language=language,
1080            date_range=date_range,
1081            page=page,
1082            public_only=public_only,
1083            slots_filter=slots_filter,
1084        )
1085
1086        return self.factory.deserialize_fireteams(resp)
1087
1088    async def fetch_clan_fireteam(
1089        self, access_token: str, fireteam_id: int, group_id: int
1090    ) -> fireteams.AvailableFireteam:
1091        """Fetch a specific clan fireteam.
1092
1093        .. note::
1094            This method requires OAuth2: ReadGroups scope.
1095
1096        Parameters
1097        ----------
1098        access_token : `str`
1099            The bearer access token associated with the bungie account.
1100        group_id : `int`
1101            The group/clan id to fetch the fireteam from.
1102        fireteam_id : `int`
1103            The fireteam id to fetch.
1104
1105        Returns
1106        -------
1107        `aiobungie.crates.AvailableFireteam`
1108            A sequence of available fireteams objects.
1109        """
1110        resp = await self.rest.fetch_clan_fireteam(access_token, fireteam_id, group_id)
1111
1112        return self.factory.deserialize_available_fireteam(resp)
1113
1114    async def fetch_my_clan_fireteams(
1115        self,
1116        access_token: str,
1117        group_id: int,
1118        *,
1119        include_closed: bool = True,
1120        platform: fireteams.FireteamPlatform | int,
1121        language: fireteams.FireteamLanguage | str,
1122        filtered: bool = True,
1123        page: int = 0,
1124    ) -> collections.Sequence[fireteams.AvailableFireteam]:
1125        """A method that's similar to `fetch_fireteams` but requires OAuth2.
1126
1127        .. note::
1128            This method requires OAuth2: ReadGroups scope.
1129
1130        Parameters
1131        ----------
1132        access_token : str
1133            The bearer access token associated with the bungie account.
1134        group_id : int
1135            The group/clan id to fetch.
1136
1137        Other Parameters
1138        ----------------
1139        include_closed : `bool`
1140            If provided and set to True, It will also return closed fireteams.
1141            If provided and set to False, It will only return public fireteams. Default is True.
1142        platform : aiobungie.aiobungie.crates.fireteams.FireteamPlatform | int
1143            If this is provided. Then the results will be filtered with the given platform.
1144            Defaults to aiobungie.crates.FireteamPlatform.ANY which returns all platforms.
1145        language : `aiobungie.crates.fireteams.FireteamLanguage | str`
1146            A locale language to filter the used language in that fireteam.
1147            Defaults to aiobungie.crates.FireteamLanguage.ALL
1148        filtered : `bool`
1149            If set to True, it will filter by clan. Otherwise not. Default is True.
1150        page : `int`
1151            The page number. By default its 0 which returns all available activities.
1152
1153        Returns
1154        -------
1155        `collections.Sequence[aiobungie.crates.AvailableFireteam]`
1156            A sequence of available fireteams objects if exists. else `None` will be returned.
1157        """
1158        resp = await self.rest.fetch_my_clan_fireteams(
1159            access_token,
1160            group_id,
1161            include_closed=include_closed,
1162            platform=platform,
1163            language=language,
1164            filtered=filtered,
1165            page=page,
1166        )
1167
1168        return self.factory.deserialize_available_fireteams(resp)
1169
1170    # Friends and social.
1171
1172    async def fetch_friends(
1173        self, access_token: str, /
1174    ) -> collections.Sequence[friends.Friend]:
1175        """Fetch bungie friend list.
1176
1177        .. note::
1178            This requests OAuth2: ReadUserData scope.
1179
1180        Parameters
1181        -----------
1182        access_token : `str`
1183            The bearer access token associated with the bungie account.
1184
1185        Returns
1186        -------
1187        `collections.Sequence[aiobungie.crates.Friend]`
1188            A sequence of the friends associated with that access token.
1189        """
1190
1191        resp = await self.rest.fetch_friends(access_token)
1192
1193        return self.factory.deserialize_friends(resp)
1194
1195    async def fetch_friend_requests(
1196        self, access_token: str, /
1197    ) -> friends.FriendRequestView:
1198        """Fetch pending bungie friend requests queue.
1199
1200        .. note::
1201            This requests OAuth2: ReadUserData scope.
1202
1203        Parameters
1204        -----------
1205        access_token : `str`
1206            The bearer access token associated with the bungie account.
1207
1208        Returns
1209        -------
1210        `aiobungie.crates.FriendRequestView`
1211            A friend requests view of that associated access token.
1212        """
1213
1214        resp = await self.rest.fetch_friend_requests(access_token)
1215
1216        return self.factory.deserialize_friend_requests(resp)
1217
1218    # Applications and Developer portal.
1219
1220    async def fetch_application(self, appid: int, /) -> application.Application:
1221        """Fetch a Bungie application.
1222
1223        Parameters
1224        -----------
1225        appid: `int`
1226            The application id.
1227
1228        Returns
1229        --------
1230        `aiobungie.crates.Application`
1231            A Bungie application.
1232        """
1233        resp = await self.rest.fetch_application(appid)
1234
1235        return self.factory.deserialize_app(resp)
1236
1237    # Milestones
1238
1239    async def fetch_public_milestone_content(
1240        self, milestone_hash: int, /
1241    ) -> milestones.MilestoneContent:
1242        """Fetch the milestone content given its hash.
1243
1244        Parameters
1245        ----------
1246        milestone_hash : `int`
1247            The milestone hash.
1248
1249        Returns
1250        -------
1251        `aiobungie.crates.milestones.MilestoneContent`
1252            A milestone content object.
1253        """
1254        ...
1255        resp = await self.rest.fetch_public_milestone_content(milestone_hash)
1256        return self.factory.deserialize_public_milestone_content(resp)